ODLink

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODLink

Superclasses
ODPersistentObject --> ODRefCntObject --> ODObject
Subclasses
none

An object of the ODLink class represents the destinations of an OpenDoc link. Instances of this class are created and maintained by draft objects whenever the user creates a link between parts.

Description
Linking is a mechanism for associating data in one part (the source) with data in another location (the destination) in such a way that the destination data can be updated either manually or automatically whenever the source data changes. A typical example of linking allows the user to paste a spreadsheet graph into a financial report in such a way that subsequent changes to the spreadsheet are automatically reflected in the report.
Links are created during paste or drop operations. The source and destination can be in the same part, in different parts in the same document, or in different documents. A link is a persistent, one-way conduit; updating occurs from the source to the destination only. Link sources are represented by ODLinkSource objects; link destinations are represented by ODLink objects.
When the user requests a link, the following events occur:

The destination part asks for a link object by calling its draft's AcquireLink method (page 153).
If the source part is in the same document, the draft calls the source part's CreateLink method (page 492). The source part may refuse this request, in which case the link cannot be created; normally, however, the source part would refuse only in the event of an error.
If the link-source object was created successfully, the draft's AcquireLink method returns a link object to the destination part.

Every link-source object has an associated update ID that uniquely identifies the current generation or version of its content. The source part sets the update ID whenever it creates or updates the content of a link-source object. The destination part stores the ID that was current when it last updated its content from the link.
The destination part reads link data from a link object's content storage unit. Because source and destination parts may attempt to access a link simultaneously, parts must acquire a lock before they can access the content storage unit. You can lock a link object by calling its Lock method (page 354); you can then obtain a reference to the link object's content storage unit by calling its GetContentStorageUnit method (page 352). You must not cache that storage unit; instead you must call the GetContentStorageUnit method whenever you need to access the storage unit.
A destination part can register itself for automatic notification of updates by calling the RegisterDependent method (page 355) of the link object. Whenever the link-source object sends updates to the link object, the link object calls the LinkUpdated method (page 533) of each of its registered destination parts to notify those parts to read the new data from the link object's content storage unit.
A destination part is responsible for updating its destination content from the link object. If your part is the destination part of a link, its LinkUpdated method should read data from the link object's content storage unit and use that data to update its destination content. In addition, after your part displays the Show Link Destination Info dialog box, it should update its destination content if the user exits the dialog box by clicking the Update Now button.
Each link destination tracks a single link source, but there can be several link destinations for any given link source. Within a given draft, a single link object is associated with each link-source object, even if the source is linked to multiple destinations in the draft; all destinations in the draft share this link object. For this reason, a part that maintains two or more destinations of a given link source must be careful to register only once with the corresponding link object.
A destination part's registration with a link is not permanent; the part should reregister when it is re-created from its stored data if the destination content is visible or if it could affect the layout of the part. A destination part may explicitly unregister itself from a link by calling the UnregisterDependent method (page 361) of the link object. A destination part with a single destination for a particular link source should unregister when the user breaks the link at the destination, when the linked content is deleted, or when the user changes the destination from automatic to manual updating. A destination part with multiple destinations of the same link source should unregister in the same situations, provided that none of the other destinations gets updates automatically.
If your part contains a link destination, you are responsible for drawing an appropriate border around the linked content when requested to do so. If the user selects any content within the link, or checks the Show Links setting of the Document Info dialog box, you must show the border of the link destination whenever you draw. You can check whether to show links by calling the window's ShouldShowLinks method (page 837) before drawing your part's content.
For further information on the implementation of OpenDoc links, see the descriptions of the companion classes ODLinkSource (page 371) and ODLinkSpec (page 390) and the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS.

Methods
This section presents summary descriptions of the ODLink methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Link Access

Lock
Locks this link object, ensuring exclusive read-only access to its content storage unit.
Unlock
Unlocks this link object, relinquishing access to its content storage unit.
GetContentStorageUnit

Returns a reference to the storage unit containing the content of this link object.
Updating

GetUpdateID
Returns the update ID that uniquely identifies the current generation or version of the link source content.
GetChangeTime
Returns the time of the last update to the link source content.
RegisterDependent
Puts the specified destination part on the list of parts to be notified whenever the link is updated.
UnregisterDependent

Removes the previously registered destination part from the list of parts to be notified whenever the link is updated.
Link Information

ShowSourceContent
Requests the source part of the link to make the source content visible.
ShowLinkDestinationInfo [M]
Displays the Link Destination Info dialog box for this link object.

Methods
GetChangeTime
GetContentStorageUnit
GetUpdateID
Lock
RegisterDependent
ShowLinkDestinationInfo
ShowSourceContent
Unlock
UnregisterDependent